home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / Wimp / Text < prev   
Encoding:
Text File  |  1988-12-06  |  8.1 KB  |  195 lines
  1. > Wimp.Text
  2.  
  3. New Calls
  4. ---------
  5.  
  6.         Wimp_ProcessKey
  7.         Wimp_Poll:  reason code 11  (Lose_Caret)
  8.         Wimp_Poll:  reason code 12  (Gain_Caret)
  9.         Wimp_SetCaretPosition
  10.  
  11.         system font size
  12.         escape handling
  13.  
  14.  
  15. System font size
  16. ----------------
  17.  
  18. In conjunction with the colour translations detailed in Wimp.Colours, the
  19. Wimp also sets up the system font size to be constant (in OS unit terms) in
  20. any mode, thus making the job of application programs easier.
  21.  
  22. Basically the system font is scaled so that it is always 16 x 32 OS units in
  23. size, whatever the resolution of the screen mode in use.  This results in
  24. double-height characters in mode 20, for example.
  25.  
  26. The basic approach is for applications to work in OS unit terms, so that if a
  27. high-resolution monitor is used, object sizes are NOT changed to reflect the
  28. size of the pixels available.  Instead, a large monitor would support a mode
  29. where the screen is more than 1280 pixels across - thus it is only the Wimp
  30. which needs to have special knowledge of the screen dimensions, since all
  31. other programs are working inside windows anyway.
  32.  
  33.  
  34. Escape handling
  35. ---------------
  36.  
  37. The Arthur 1.20 Wimp left escape handling up to the current application,
  38. which meant that the application was responsible for acknowledging escape
  39. after it had detected it.
  40.  
  41. In a multi-tasking world, however, the handling of escape must be done
  42. differently.  The Wimp actually programs the escape key to return the ascii
  43. code 27, and so it is the application which owns the caret that deals with
  44. escape.  No escape events or escape conditions are generated.
  45.  
  46. If an application wishes to use escape in the old way, it is only allowed to
  47. do this as long as it is not calling Wimp_Poll.  Thus, if the application
  48. intends to perform some long-winded operation without calling Wimp_Poll, it
  49. might re-enable escape (*FX 229,0) during the operation to allow it to be
  50. aborted.  If it does so, it must reset the escape key state (*FX 229,1)
  51. before it calls Wimp_Poll again.  Note that when restoring the escape key
  52. state it is also necessary to acknowledge escape (*fx 126) AFTER the *fx 229,1.
  53.  
  54. Note that when the Wimp finally exits, it restores the escape handling status
  55. to that when it was first invoked (along with function keys, cursor keys etc).
  56.  
  57.  
  58. Wimp_ProcessKey / soft keys
  59. ---------------------------
  60.  
  61. Wimp_ProcessKey was available in Arthur 1.20, but has now been improved to
  62. allow for soft key expansion in writeable icons, as follows:
  63.  
  64.      *  when a function key is pressed, the equivalent code is returned to
  65.         the application which owns the input focus (whether or not the caret
  66.         is inside a writeable icon).
  67.                   f0-f9 return &180 to &189
  68.                 f10-f12 return &1CA to &1CC
  69.  
  70.      *  the application may wish to perform some explicit function on receipt
  71.         of the function key code, but if it does not it should pass the code
  72.         on to Wimp_ProcessKey (R0 = key code) - indeed, any unrecognised key
  73.         should be passed to Wimp_ProcessKey.
  74.  
  75.      *  if a function key code is passed to Wimp_ProcessKey, and the caret is
  76.         inside a writeable icon, the Wimp will automatically expand the soft
  77.         key definition and insert it in the icon.
  78.  
  79. The above interface is back-compatible with Arthur 1.20, in that function
  80. keys are initially returned to the application, but allows the application
  81. very simply to convert the function keys into soft key expansions.
  82.  
  83. It also allows other utility programs to provide a 'hot key' facility,
  84. whereby a special function key code performs some function, without the
  85. application needing to have the input focus.
  86.  
  87. If bit 12 of a window's flag word is set (wf_grabkeys), then any calls to
  88. Wimp_ProcessKey will be passed on to the window if it is open.  The Wimp will
  89. call the topmost window with this bit set first: if the application
  90. recognises the code, it should act on it, but if it does not it should call
  91. Wimp_ProcessKey with the same code, thereby passing it on to any other
  92. windows with this bit set.  The Wimp simply returns a Key_Pressed event to
  93. the application from Wimp_Poll: note that the values in the block refer to
  94. the position of the actual input focus at the time, which may not necessarily
  95. be the same as the window with the wf_grabkeys bit set.
  96.  
  97. If an application wishes to grab keys, but does not want any windows to be
  98. visible, it should open a window off the visible screen area with bit 6 set
  99. (wf_nochecks).  Negative x-coordinates are to be preferred to large positive
  100. ones, since the screen size should not be assumed in advance!
  101.  
  102. If no applications grab the key code, the Wimp will give up and expand the
  103. soft key string if the key was a function key, and the caret is in a
  104. writeable icon.
  105.  
  106. NOTE:  It is not a good idea for the application to act on the key, and then
  107.        also pass it on.  This kind of behaviour is not helpful to the user!
  108.  
  109.  
  110. Lose_Caret
  111. ----------
  112.  
  113. The Wimp_Poll reason codes 11 and 12 (Lose_Caret and Gain_Caret) have been
  114. added so that, if an application displays its caret itself, it can remove it
  115. from the screen when another application takes it away.
  116.  
  117. Wimp_Poll
  118. Exit:  R0 = 11
  119.        R1 --> block:
  120.            R1!0 = window handle of window which HAD the caret
  121.            R1!4 = icon handle
  122.            R1!8 = x-offset in window
  123.            R1!12 = y-offset in window
  124.            R1!16 = caret height/flags
  125.            R1!20 = index
  126.  
  127. In theory the application might wish to display some sort of 'stunted' caret
  128. in place of the real one, to show where the caret would reappear if it was
  129. returned to the window (NB useful if select-block / copy-block used between
  130. windows - the actual caret may have moved to a dialogue box in the middle of
  131. this operation, but one still wants to know where the destination of the move
  132. is).
  133.  
  134.  
  135. Gain_Caret
  136. ----------
  137.  
  138. Wimp_Poll
  139. Exit:  R0 = 12
  140.        R1 --> block:
  141.            R1!0 = window handle of window which HAS the caret
  142.            R1!4 = icon handle
  143.            R1!8 = x-offset in window
  144.            R1!12 = y-offset in window
  145.            R1!16 = caret height/flags
  146.            R1!20 = index
  147.  
  148.  
  149. Wimp_SetCaretPosition
  150. ---------------------
  151.  
  152. If the window handle is changing, then a lose_caret message is generated for
  153. the old caret position, and a gain_caret message is generated for the new
  154. position - note that the caret position may be restored to a position which
  155. is not owned by the task which is calling Wimp_SetCaretPosition.
  156.  
  157. Note that the messages are generated even if the windows are both owned by
  158. the same task, and irrespective of whether the application is in control of
  159. the caret, or the Wimp is (eg. caret inside a writeable icon).
  160.  
  161. The specification of R4 (caret height) in this call has been extended:
  162.  
  163.      R4 bits  0..15 =  caret height (OS units)
  164.         bits 16..23 =  caret colour (if bit 26 set)
  165.         bit  24 set => use VDU-5 type caret, else font manager caret
  166.         bit  25 set => the caret is invisible (application must draw it)
  167.         bit  26 set => bits 16..23 are the caret colour (else Wimp colour 11)
  168.         bit  27 set => bits 16..23 are a 'real' colour, else Wimp colour
  169.  
  170. If bits 26 and 27 are set, the caret is plotted by EORing with the colour in
  171. bits 16..23 (in 256-colour modes, bits 16,17 are bits 6,7 of the tint, while
  172. bits 17..23 are the gcol colour).
  173.  
  174. If bit 26 is set and bit 27 unset, then bits 16..23 represent a Wimp colour
  175. (in the range 0..15).  In this case the caret is plotted by EORing with the
  176. 'real' colour associated with this wimp colour EORed with the real colour for
  177. Wimp colour 0.
  178.  
  179. If bit 26 is unset, the caret is drawn by EORing with the EOR of Wimp colours
  180. 0 and 11 (so that the caret will appear as wimp colour 11 when plotted on a
  181. background of wimp colour 0).
  182.  
  183. Note that if you wish to display the caret on a background which is not Wimp
  184. colour 0, you must perform the following:
  185.  
  186.      *  SWI Wimp_ReadPalette to discover the real colours associated with
  187.         your background colour and your proposed caret colour (the bottom
  188.         byte of each palette entry is the gcol value used for it).
  189.  
  190.      *  EOR these two colours together, and put in bits 16..23 of R4
  191.      *  set bits 26 and 27 of R4
  192.  
  193. See Wimp.Colours for further details of how the caret colour is set.
  194.  
  195.